Event Streams REST API

The Event Streams REST API allows applications using HTTP-based operations to produce messages seamlessly. It supports both multiple messages in a predefined JSON format and single messages without a predefined format. The single message option enables direct messaging in its original format, eliminating the need for data transformation.

With the introduction of the REST API, customers can now produce messages with a size of up to 5MB.

Getting Started

To use the REST API in Event Streams:

1. Log into the Boomi Platform.
2. Navigate to the Event Streams feature by clicking on the Event Stream tile from the dashboard.
3. Locate and click on the Environment tab to view available environments.
4. Drill down to the Topics table for each environment to see the specific topics associated with it.

Copying REST API URL

Each topic has a unique REST API that allows you to produce messages. To copy the URL:

1. Navigate to the desired topic within the Topics page or Environment Overview page.
2. Click on the View REST link in the connections column of the topic. A side drawer will open, displaying two tabs. Single Message and Multiple Messages. Once opened, the tab will display the REST URL and other required information.
3. Click on the Copy URL button to copy the URL to your clipboard.
4. A success message (e.g., "Copied to Clipboard") will appear, confirming the action.

Message Size and Rate Limits:

• Maximum message size produced via the Connector is limited to 1MB. Maximum message size produced via the REST API is limited to 5MB.

• For consume with Acknowledge operation enabled, the limit is 10 messages per execution and supports up to 20 concurrent consumers at a time. Additional consumers created will receive an error message which can be seen in the Process Reporting page.

• The rate limit for the Event Streams REST API is set as 60,000 requests per IP within a 5 minute window. The total size of the HTTP request must not exceed 10MB.

Other Event Streams Usage limits:

• Environments: A maximum of 200 Environments are allowed per account.
• Topics: Each Environment can have up to 1000 topics.
• Backlog: Topics can store a maximum of 5GB of backlog data.
• Tokens: Each Environment can have up to 1000 tokens.

Constructing the API Request

To produce a message, you will need to send an HTTP POST request to the copied REST API URL.

• Multi message have a predefined format and payload is stringed from the original message like in the screenshot
• Single message can be in original format (e.g. plain text, JSON, XML) without the need for data transformation

Message Payload Structure for Multiple Messages:

The request must include a JSON body structured as follows:

{
    "messages": [
        {
            "payload": "SampleTestPayload1",
            "properties": {
                "key1": "Value1",
                "key2": "Value2",
                "key3": "Value3"
            }
        }
    ]
}

Multiple messages can be produced in one call by adding more messages to the payload as follows,

{
    "messages": [
        {
            "payload": "SampleTestPayload1",
            "properties": {
                "key1": "Value1",
                "key2": "Value2",
                "key3": "Value3"
            }
        },
        {
            "payload": "SampleTestPayload2",
            "properties": {
                "key1": "Value1",
                "key2": "Value2",
                "key3": "Value3"
            }
        }
    ]
}

Parameter	Required?	Type	Description
payload	Yes	String	The actual message payload being sent
properties	No	Map<String,String>	Custom properties that can be included as metadata.

Recommendation for multiple Messages REST API: Avoid using spaces in properties. Though creating message properties with spaces will still allow for message production and consumption, they will not be visible on message management.

Recommendation for Single Message REST API:

• Message properties are sent via request headers, each corresponding to a property. The header name must start with 'x-msg-props-', followed by the property name. which is key sensitive.

• The content type must match with data sent in the message body (e.g. application/JSON). The content type is recorded as a message property for viewing or downloading in Event Streams.

Authorization

To authenticate the API request, use the Environment Token as a Bearer Token. Be sure to include the token in the Authorization header of your request as shown below.

Authorization: Bearer YOUR_ENVIRONMENT_TOKEN

Using Postman to create an Example Request

To use Postman to send a message to your topic, follow the instructions below:

1. Open Postman and create a new POST request.
2. Enter the copied REST API URL in the request URL field.
3. In the Headers tab, set the following:
   • Key: Authorization
   • Value: Bearer YOUR_ENVIRONMENT_TOKEN
4. In the Body tab, select raw and choose JSON as the format.
5. Paste the message payload structure from above.
6. Click Send to produce the message.

Viewing Produced Messages

Once a message has been successfully sent, you can view it in the Message Backlog via the Message Management UI by following these steps.

1. Return to the Event Streams feature.
2. Click on the Message Management section.
3. Select the relevant topic to review incoming messages.

Additionally, after sending a message through a REST client such as Postman, you can confirm successful delivery by checking for an HTTP 200 response code along with a list of message IDs. This indicates that the messages have been acknowledged by the broker. For example:

{
  "status": "success",
  "messageIds": "744:7:0,744:8:0,744:9:0,744:10:0"
}

Troubleshooting

If you encounter issues while using the REST API for message production:

• Check Authorization: Ensure that the Environment Token used is correct and has the necessary permissions.
• Validate Payload: Confirm that the JSON body structure is correct and includes all required fields.